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Preface 


This document is an introduction the the PL-6 system programming Language used 
to create and maintain the CP-6 Operating System. 


Computer Aided Publication (CAP) is an advanced electronic technical 
publishing system. The Honeywell Bull Los Angeles Development Center (Product 
Development Organization) Documentation Services group authors, edits, 
reviews, and creates laser print masters with integrated text and graphics 
using CAP. This manual is a product of CAP. 


Readers of this document may report errors or suggest changes through a STAR 
on the CP-6 STARLOG system. Prompt response is made to any STAR against a 
CP-6 manual, and changes will be incorporated into subsequent releases and/or 
revisions of the manuals. 


The intormation and specifications in this document are subject to change 
without notice. Consult your Honeywell Bull Marketing Representative for 
product or service availability. 


Copyright (c) Honeywell Bull Inc., 1988 Fite No.: 
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About This Manual 


This manual is a beginner's guide to the PL-6 programming language. It was 
originally prepared for college course-Level instruction at IUP (Indiana 
University of Pennsylvania), a CP-6 educational site. It is currently in a 
form appropriate for that environment, but someday, the section on 1/0 at the 


end will be redone to reflect proper usage of CP-6 Monitor Services directly 
from the CP-6 system. 
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Syntax Notations 


Table 1. Notation Conventions Table 
Notation Description 


Lowercase 


Lowercase Letters identify an element that must be replaced 
by a user-selected value. For example, in a TEXT macro the 
value: 


“figure title" indicates the user supplies a 


value for figure title. 


CAPITAL LETTERS 


Capital letters indicate a literal, to be entered as shown. 
For example: 


FIG "figure title” indicates that the value FIG 
must be entered as shown. 


Special Characters 


The character * has a special function and is to be entered 
as shown. Likewise the combination of characters ..: is 
used to introduce CAP macros and must be entered as shown. 
The period is used to introduce TEXT control words. 


Carated Letters 


Letters inside carats (< >) identify physical keys on the 
terminal. Carats are not typed. The indicated keys are 
pressed. 


<CR> indicates touch the RETURN or NEWLINE key. 
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Table 1. Notation Conventions Table (cont) 
Notation Description 


Brackets 


Brackets are used to enclose an optional element. If more 
than one element is enclosed in brackets, the notation 
indicates an optional choice. Multiple elements in brackets 
can be stacked or separated with the OR bar. For example: 


Cid] 


Lid] or [idta] indicates that a value for id or 
[A ] the Literal A may be entered. 


indicates that a value for id may be entered. 


When enclosing keywords, brackets signify that all or part 
of the bracketed portion may be entered. 


K[EY] indicates KEY can appear as K, KE, or KEY. 


Braces 


Braces are used to enclose a required choice: one of the 
elements enclosed in the braces must be selected. The 

elements can be stacked or separated with the OR bar. For 
example: 


{A } or {Al id} both mean that either the 
{id} Literal A or a user-supptied 
value for id must be selected. 


The OR bar separates elements enclosed in braces or brackets 
from which one may or must be chosen. 


{Al id} means that either the letter A or the 
value of id must be entered. 
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Table 1. Notation Conventions Table (cont) 
Notation Description 


Horizontal Ellipsis 


The horizontal ellipsis indicates that an element can be 
repeated. For example: 


#data#data...#data indicates that the user can 
supply multiple data fields, 
each one separated from the 


preceding field by the #. 


Vertical Ellipsis 


The vertical ellipsis indicates that something has been 
omitted purposely. For example: 


This is the first Line of text 
FH indicates that text Lines 
: have been omitted. 


This is the Last Line of text. 
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Section 1 


PL-6 IN A NUTSHELL 


PL-6 is the CP-6 system implementation language. It provides for efficient 
block structured programming of tasks that are closely related to the 
operation of the system, for example, compilers, assemblers, simulators, and 
communication packages. PL-6 has a variety of data types, flexible control 
Statements, and a simple syntax. It also provides easy access to the monitor 
services of CP-6. 


Basic Forms 


A PL-6 program is organized into procedures. One of these procedures is 
designated as the MAIN procedure or program. Other procedures can be 
considered subroutines. These procedures may be declared inside or outside 
the main procedure. All procedures begin with a PROC statement and end with 
an END statement. 


Identifiers in PL-6 may be formed using any of the following characters: A 
through Z, 0 through 9, #, $, @, and _. The first character must be 
alphabetic and the number of characters less than 31. Each statement in a 
Procedure must be ended with a semicolon (;). Each statement may have a 
label. A label has the same form as an identifier, must be to the left of the 
statement, and must end with a colon (:). Commas are used to separate 
portions of certain statements and the apostrophe is used to delimit string 
constants. 


The arithmetic operators are: 


(add) 
(subtract) 
(multiply) 
(divide) 


Ne 1+ 


There is NO exponentiation. 
There are NO floating point values. 
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The relational operators are symbolic: 


= for equal 

< for less than 

> for greater than 

<= for less than or equal 

>= for greater than or equal 
~= for not equal 


The Logical operators are: 


~ for "not" 
| for "or" 
& for "and" 


\ for "exclusive or" 


The keywords "NOT", "AND", and "OR" may also be used with truth-value 
expressions in IF and DO statements. 


Logical operators work on bit-string values, performing bit-by-bit 
operations. 


NOT, AND, and OR work on bit-strings and evaluate to truth values; if 
ANY bit of a named variable is 1, its truth value is TRUE. 


Parentheses and the equal sign (=) have the usual meaning in assignment 
statements. The beginning and end of a comment are denoted by "“/x" and "x/", 
respectively. The symbols "->" are used in associating a pointer with a based 
variable. 


Declarations 


ALL identifiers (names) must be declared using the DCL statement. ALL DCL 
statements for a procedure must appear at the beginning of the procedure. A 
declared identifier is known in all procedures contained within the procedure 
in which it is declared. Only ONE variable, array, or structure can be 
declared with each DCL statement. The forms of the DCL statement are shown 
below. 


DCL id [attributelist]; To declare a variable 
named ''id". 


DCL id (O:b) [attributelist]; To declare the array “id” 
that has elements 0 to b. 


DCL level1 id1 [attributelist1] [, leveln idn attributelistn]; 


, 
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To declare a structure. The top level (level1) 
is 1; other levels (leveln) may 2 through 10. 
This is similar to a COBOL record, except 

that levels may not be skipped. Also, 

* may be used in place of an identifier name 
for an "“idn" in order to denote "filter". 


There are four types of attributes that may appear in an attribute List ina 
DCL statement: data type, alignment, storage class, and special. A data type 
should be declared for each identifier (except for the level 1 name in a 
Structure). The data type attributes are Listed below. 


Attribute Meaning Default Alignment 
SBIN(n) Signed binary integer ALIGNED 

UBIN(n) Unsigned binary integer ALIGNED 

CHAR(c) Character string CALIGNED 

BITC b) Bit string UNAL 

PTR Pointer to another variable ALIGNED 


The "n" in parentheses after the attribute name is optional. If it is 
included, it represents the number of bits used to represent the integer. If 
“n' is not used, the default size is 36 bits. For SBIN and UBIN, a size may 
be specified by keyword instead of using "n'". The form is "SBIN size" or 
“UBIN size" where "size" is WORD (same as n=36), HALF (same as n=18), or BYTE 


(same as n=9). 


The "c"’ represents the number of characters in a character string. Each 
character of the string may be accessed individually through the use of 
several built-in subroutines. The "b'’ represents the number of bits in a bit 
string. 


An alignment attribute may be specified for any identifier that has a data 
type. If an alignment other than the default is to be used, it must be 
specified in the DCL statement. The alignment attributes indicate how storage 
shoutd be allocated for an identifier. The following List indicates the 
storage boundaries used for various alignments. 


Attribute Beginning and ending boundary unit 
ALIGNED Word 

CALIGNED Byte 

DALIGNED Even numbered word 

HALIGNED Half word 

WALIGNED Word (same as ALIGNED) 

UNAL Bit 
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The storage class of an identifier determines how permanent it is and where it 
is known. The storage class may be specified for any identifier. A List of 
most storage classes and their meanings follows. 


Class Meaning 

AUTO Storage is allocated for the identifier each time 
the procedure is called. Storage is released 
when the procedure is exited. 


STATIC Storage is allocated throughout the running of 
the program. 


CONSTANT Storage is allocated to contain a constant value. 
The value cannot be changed. 


EXT The identifier may be referenced outside the 
procedure in which it is declared. 


DCB Storage is allocated for a data control block. 
Other attributes cannot be used with this one. 


SYMREF Indicates that the identifier refers to the same 


SYMDEF in another procedure. 


BASED No storage is allocated for the identifier, only 
a storage template is made. The template is 
associated with storage through the use of a 
pointer variable. 


The special attributes are used to indicate special properties associated with 
an identifier. The following is a List of the most important special 
attributes. 


Attribute Meaning 
SYMDEF Specifies that the identifier may be referred to 
with a SYMREF in another procedure. 


REDEF Specifies an alternate description for a previously 
declared storage area. Note: the sizes must match. 


ENTRY (n) Specifies that the identifier is an external 
procedure name. The "n"' represents the number of 
parameters the procedure has; '"(n)" can be omitted 
if it is zero. 
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ALTRET Specifies that an external procedure can have 
an ALTRETURN. 


INIT Specifies starting values to be assigned to 
identitiers. An array may be initialized by 
Listing individual elements or by specifying 
entries of the form “valuezxr'’ to repeat the 
“value"’ r times. Note: ‘“valuex0" repeats the 
value enough times to fill the unspecitied 
portion of the array. 


Based Data Structures 


Most Languages associate one or more specific memory locations with each named 
data item. This is also true of most data items in PL-6. However, PL-6 also 
provides the capability of defining simple or complex data structures that are 
not directly associated with any memory locations. Such data items are said 
to be "based" and have a declaration similar to the following one. 


DCL ABC(0:9) CHAR(1) BASED; 
ABC is declared to be an array of 10 single characters, but no storage is 
allocated to hold the array. Instead, only the template (or form) of the 
array is set up. The template is associated with memory locations through the 
use of a pointer variable. For example: 


DCL PS PTR; 
DCL STR CHAR(10) STATIC; 


declares P$ to be a pointer and STR to be a string of 10 characters. 
By assigning P$ the address of STR, the ABC structure can be overlayed onto 
the Locations allocated to STR. P$ is assigned the address by a statement 
such as: 

PS = ADDR(STR); 
(See the Built-in Functions section for a description of ADDR.) Then the 
following statement shows a pointer-qualified reference to ABC which causes an 
asterisk to be put in the 4th element of ABC, that is, the 4th character of 
STR. 

P$ -> ABC(3) = ‘x'; 


Note: P$ can also be used in association with other templates. 
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Pointer qualification can be explicit (as in the previous example) or 
implicit. Implicit qualification occurs when a pointer variable is associated 
with a based data item in the DCL statement, for example: 


DCL XYZ(0:4) CHAR(2) BASED P$; 


Here XYZ is a based variable that is automatically associated with the P$ 
pointer, unless it is explicitly pointer qualified with another pointer. 
Thus, the following two statements are equivalent. Both set the 4th and 5th 
characters of STR to blank. 


XY¥Z(2) = ' ': 
P$ -> XYZ(2) = ' ‘3 


Based data items and pointer variables are particularly useful in dealing with 
Linked data structures. 
Assignment Statements 
The form of an assignment statement is: 

target = expression; 
The validity of such statements depends on the syntax of the expression and of 
the value types of the target and expressions. The following List describes 


the valid combinations of value types; where possible, the data type of the 
target is shown. 


Target Expression type Special action 

SBIN or Arithmetic High order bits are Lost 
UBIN if target field is too small. 
CHAR Character string If target shorter, truncate 


on the right. If target is 
Longer, extend on the right 
with blanks. 


BIT or Bit string If target is shorter, truncate 
array or on the right. If target is 
structure Longer, extend on the right 


with zero bits. 


PTR Pointer None, but value must be ADDR 
of a location. 
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The following List indicates the order of precedence in evaluating an 
expression in an assignment statement. The List is in order from highest to 
lowest. 


Order of precedence by operation symbol: 


~, unMary -, unary + 

x, / 
binary -, binary + 
<, <c, >, >=, =, ~2 
& 

1, 
NOT 
AND 
OR 


\ 


Control Statements 

f 
There are three statements of the control type in PL-6 that are of interest. 
They are IF, DO, and EXIT. Each of these is described below. The IF and DO 
have more than one form. 


There are two forms for the IF statement: 


IF exp THEN stmt; 
and 
IF exp THEN stmtiz; ELSE stmt2; 


The “exp” is a bit-string or truth-value expression. The "stmt'' in each IF 
May be almost any executable PL-6 statement or a DO block. Each “stmt'' may 
have a label. For nested IF statements, each ELSE goes with the nearest 
unELSEd IF. 


The DO statement has at least six forms that you may find useful. The 


simplest DO is not a control statement at all; it is a way of making a 
compound statement. Its form is: 


DO; 
Following the DO are a series of statements which are collectively treated as 
a single statement. The end of the series of statements is marked with an END 
statement. This collection of statements is referred to as a DO block and can 
usually appear anywhere a single statement can occur. 


DO CASE (exp); 
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The “exp” is an arithmetic expression or variable, a UBIN value. This 
statement is followed with a series of CASE statements of the form: 


CASE (const,const,...); 
The "exp" in the DO CASE is evaluated and matched against each of the CASE 
constants ("const"). When a match is found, the statements associated with 


that CASE statement are performed. 


An example is shown at the right. 


Each "const'' must be a constant DO CASE (K); 

at compile time. The series of CASE (0); J=J+1; 
CASE statements is terminated with CASE (1,3); J=J+2; 
an END statement. The "const" may be CASE (ELSE); J=0; 
the word ELSE to cover all other cases. END; 


The example increments J by 1 if K 
is 0, by 2 if K is 1 or 3, and sets 
J to zero otherwise. 


DO SELECT (exp); 


The "exp" may be any type of expression, representing a UBIN, SBIN, CHAR, or 
BIT value. This statement is followed by a series of SELECT statements of the 
form: 


SELECT (const,const,...); 


Each of the constants ("const'') must be of the same type as the "exp" in the 
DO SELECT statement. The “exp"’ is evaluated and matched against the 
constants. When a match is found, the statements associated with that SELECT 
statement are performed. As with the DO CASE, ELSE may be used in place of a 
constant in a SELECT statement. 


DO var = exp1 TO/DOWNTO exp2 [BY exp3]; 


The ''var'' is a scalar variable (not part of a structure); "exp1" is the 
initial value for "var"; "exp2" is the Limit for "var"; and "“exp3" is the 
increment for “var''. The default increment is +1 for TO and -1 for DOWNTO. 
Exp3 must be greater than 0 for the TO form and must be less than 0 for the 
DOWNTO form. This DO statement works Like the FOR statement in FORTRAN, 
except that the test is made at the top of the loop. It is delimited by an 
END statement. (The DO statement in FORTRAN is implemented differently.) 


DO WHILE (exp); 
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The “exp'' may be a bit-string or truth-value expression. The DO WHILE 
Statement is followed by a series of statements which are executed repeatedly 
as long as the “exp" is true. The series of statements is delimited by an END 
statement. The statements inside the DO WHILE loop may be any executable PL-6 
Statements. The check of the expression is made at the beginning of the loop. 


DO UNTIL (exp); 


The "exp" may be a bit-string or truth-vaLue expression. The DO UNTIL 
statement is followed by a series of statements that are executed repeatedly 
until the "exp" is true. The series of statements is delimited by an END- 
Statement. The statements inside the DO UNTIL Loop may be any executable PL-6 
Statements. The check of the expression is made at the end of the loop. 


The EXIT statement has the form: 
EXIT [labet]; 


This statement is used to escape from a DO loop. The simple form of the 
Statement (EXIT;) jumps to the statement after the END of the innermost DO 
which the EXIT statement is in. To get out of several Levels of nested DO 
loops, the other form (EXIT label>) is used. The EXIT Label; jumps to the 
Statement after the END of the DO Loop which has the specified Label on its DO 
Statement. The DO loops from which the EXIT escapes may be any of the forms 
of the DO described previously. 


Procedure Related Statements 


There are five procedure related statements that you will be using frequently. 
Each of them is described below after their format is shown. 


entry: PROC MAIN/(parameterlist) [ALTRET]; 


Only one PROC in a program is the MAIN PROC. ALt other PROCs are subroutines 
and have parameter Lists. The parameter List is a sequence of identifiers 
separated by commas. They correspond to the dummy parameters in a FORTRAN 
subroutine. The declarations of the dummy parameters in a procedure must 
match the declarations of the parameters in the procedure from which it is 
called. The “entry” is the name by which the procedure is called. 


A PROC may be internal or external. An internal PROC is wholly contained 
within another procedure. Internal procedures are known only to the 
procedures they are contained within. Internal procedures cannot be 
recursive. An external procedure is not contained within any other PROC. To 
be performed, a PROC must be called; execution cannot “fall into” a PROC. 
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The use of "“ALTRET' in the PROC statement enables the use of the ALTRETURN 
statement within the procedure to cause special action to be taken when 
control is returned from a call. 


CALL ref [(parameterlist)] [WHENALTRETURN DO; ... END]; 


The CALL statement is used to invoke a procedure. The "ref" may be an entry 
point for a procedure or it may be the name of an EPTR variable (such 
variables are not described in this document). The arguments in the parameter 
List must match those in the definition of the PROC being called. The 
WHENALTRETURN clause specifies a DO block of statements that should be 
performed if the called procedure does an ALTRETURN. Both internal and 
external procedures can be invoked with the CALL statement. ALL parameters 
are passed by reference; that is, the main program variable and associated 
subroutine variable refer to the same Location. 


RETURN; and ALTRETURN; 


These two statements are used to return control from a called PROC. For 
ALTRETURN, control is returned to the DO block specified with the 
WHENALTRETURN in the CALL statement and then continues with the statement 
after the CALL. For RETURN, control is returned to the statement after the 
CALL statement. If ALTRET is not specified in the PROC definition, ALTRETURN 
does the same thing as the RETURN. ALTRETURN is normally used to indicate an 
error condition within the called procedure. 


END [id]; 


The END statement is used to mark the end of a procedure or DO block. For a 
DO block there is no "id''. For a PROC, the "id" is the entry name of the 
procedure. 


Scope of Variables 


Variable names declared in a procedure are known in all procedures that are 
internal to the one in which the declaration is made. If the same variable 
name is redeclared in the internal procedure, the internal declaration 
overrides the outer declaration, but only within the internal procedure. 
Variables declared in procedures which are disjoint are unknown in the 
disjoint procedures. unless they are specially declared with the EXT or 
SYMDEF attributes. . 


The portion of a program in which a variable is known Cis accessible) is 
referred to as the scope of the variable . As an example of scope, consider 
the following program: 


FIRST: PROC MAIN; 
DCL A CHAR(1); 
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DCL B SBIN; 


SECOND: PROC; 
DCL A SBIN; 
DCL C UBIN; 


END SECOND; 
THIRD: PROC; 
DCL D CHAR(1); 


END THIRD; 
END FIRST; 


Here, A refers to the same CHAR(1) location in FIRST and THIRD. In SECOND, A 
jis a SBIN Location that is unrelated to A in the other procedures. Variable C 
is known only in SECOND; variable D is known only in THIRD; variable B is 
known everywhere in the program. 


Because of the way the scope of a variable can be used to pass values between 
nested procedures, internal procedures rarely have parameters. 


Built-in Functions and Subroutines 


There are many functions and subroutines built in to PL-6. These perform 
various tasks, such as string manipulation, base conversion, and pointer 
Manipulation. The most important functions and subroutines that you will need 
are Listed below and described briefly. Note: as with FORTRAN, functions are 
invoked by using their name and subroutines are invoked by the use of a CALL 
statement. 


ADDR (ref) 
ADDR is a function that returns a pointer value that identifies the storage 
location referred to by "ret". It is useful in assigning values to 
identifiers of type PTR. ADDR may be used in an INIT. 

ASCBIN (char-exp) 
ASCBIN is a function that converts a single character into a binary integer. 
The Length of the "'char-exp" must be one. The integer is returned as 
UBIN(36). 


BINASC (exp) 
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BINASC is a function that converts the low order 9 bits of the value of the 
arithmetic “exp' to a single character. The “exp'’ may be UBIN or SBIN. The 
returned result is CHAR(1). Related function: BITASC which works with a bit 
expression rather than a numeric one. 


MOD (div,dsr) 


MOD is a function that returns the remainder when "div" is divided by "dsr". 
Both "div" and "dsr" may be arithmetic expressions. The remainder has the 
same sign as the "div". 


PINCRW (ptr ,nword) 


PINCRW is a function that returns a pointer value equivalent to incrementing 
the pointer (ptr) by a specified number of words (nword). The value of nword 
may be positive or negative. Related functions: PINCRC to increment a 
pointer by a specified number of characters and PINCRB to increment a pointer 
by a specified number of bits. 


POFFW (ptr1,ptr2) 


POFFW is a function that returns a signed value that represents the positional 
relationship in words between two Locations pointed to by ptr’1 and ptr2. The 
pointers must point to locations in the same data segment and the bit and 
character offsets of the pointers must be the same. Related function: POFFC 
returns a value that represents the positional difference in characters 
between the two pointer values. 


CALL BINCHAR (str, val); 


BINCHAR is a Subroutine that converts a binary integer to a character string 
with no spaces and no sign characters. The "str" is the resultant string and 
must be of type CHAR. Leading zeros are supplied to fill the field if 
necessary. The "val" may be of type SBIN or UBIN; it may also be an 
arithmetic expression that evaluates to one of these types. If the result 
does not fit in "str", it may be truncated or an error may occur. Related 
subroutine: BINXCHAR which puts a leading sign character on the character 
string. 


CALL CHARBIN (ref, str); 
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CHARBIN is a Subroutine that converts an unsigned character string of decimal 
digits to a positive binary value. The "ref" is the Location to contain the 
binary value; the "str" is the CHAR variable containing the character string. 
If there is an illegal character in the string, an error occurs. If the 
binary value will not fit in the ref Location, it may be truncated or an error 
May occur. Related subroutine: XCHARBIN which accepts a sign character at 
the beginning of the character string. 


CALL CONCAT (tostr,stri [,str2]}...[,str6]); 


CONCAT is a subroutine that concatenates up to six strings to form a single 
string. The "tostr" is the destination, the character location where the 
concatenated string is to be stored. Each of the "str's is a character 
expression that is to be concatenated. If "tostr" is larger than the formed 
string, it is right-filled with blanks. If it is smaller, the concatenated 
string is truncated on the right. If truncation occurs, an ALTRETURN is used 
and may be handled with a WHENALTRETURN. 


CALL INDEX (index, str1, str2, [, [start] [,mask]]): 


The INDEX subroutine locates the first or next occurrence of a string within 
another string using a left to right scan. The "index" is the character 
position number at which the found string begins. The “stri" is the string 
which is to be found; “str2" is the string to be searched. If “start" is 
specified, it must be in the range 0 to the length of "str2". If "stri" is 
not found, the index is set to the length of "str2" and ALTRETURN is taken, if 
WHENALTRETURN is specified. A ‘mask'' may be specified if only portions of the 
characters are to be compared. The "mask" is specified as a literal value and 
indicates which bits of the characters are to be considered. Related 
subroutine: INDEXR which uses a right to left scan to locate the occurrences 
of a substring. ; 


SUBSTR (stri, start [,len]) 


SUBSTR is a function that extracts part-of a character string for use in a 
character expression. The "stri" is the string from which the substring is to 
be extracted. The "start" is the character position of the first character in 
the substring. The "len" is the length of the substring. When "Len" is not 
specified, the substring is assumed to begin at "start" and go to the end of 
“stri". SUBSTR may also be used on the left side of an assignment statement 
to replace a portion of a string with the value of a character expression. 


CALL INSERT (tostr, [start], [len], str1 [,str2]...[,str6]); 
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The INSERT subroutine allows up to six strings to be concatenated and then 
inserts the resultant string into another string. Each of the "str'’s is used 
in the same way as for the CONCAT subroutine. The "tostr” is a reference to 
the string into which the insertion is to be made. The "start" indicates 
where in "“tostr’ the insertion is to be made and "Len" indicates how many 
characters are to be inserted. The sum of the values of "start" and "len" 
must be Less than the Length of ‘“tostr". Truncation and blank filling occur 
based on the size of “Len” and the concatenated expression in the same way as 
for CONCAT. 


Input and Output 


Input and output in PL-6 must be done with the aid of monitor service calls. 
ALL monitor service calls are done with the CALL statement and each of them 
has a name that begins with M$. The principal monitor services that you will 
need are involved with opening, reading, writing, and closing a file. 


Many of the monitor service calls require the set up of a rather elaborate 
data structure. There are macros defined to make the creation of these data 
structures as simple as possible. The macros are kept in several files under 
the account :LIBRARY. To gain access to the macros all you have to do is 
place the following statement in your PL-6 program: 


“INCLUDE CP_6; 


Because the macros contain a number of declarations, you should place the 
statement among the DCL statements in your program, perhaps right at the end 
of your own DCLS. 


Fach of the macros is invoked by using a statement of the form: 
%macroname [(refid=string[,refid=string]...)]; 


Many of the macros that you will need have names of the form ZFPT_name, where 
FPT stands for Function Parameter Table, and ''name" is the name of the 
associated function. For example, ZFPT_OPEN is used in conjunction with 
opening a file. The function parameter table is the data structure the 
monitor service call requires to perform the function. Each monitor service 
call takes one parameter, the name of the FPT that is associated with the 
call. 


The "retid's in each invocation of the macros depend on the function to be 
performed. One "refid’ that can be used with each FPT macro is FPTN which is 
used to specify the name of the FPT structure. This name can be used in other 
references to the structure. The following List shows some of the most common 
macros, the associated monitor service call and the "refid’s that are usually 
specified. Nearly all "refid’s have default values which are used if they are 
not specified. 
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Macro M. Service Refids and strings 

FPT_OPEN MSOPEN DCB=dcbname, NAME=variable holding 
the file name, ASN=FILE for disk files, 
FUN=function (IN, UPDATE or CREATE), 
ACCTevariable holding account name, 
EXISTestatus (NEWFILE or OLDFILE) 


FPT_READ MS$READ DCB=edcbname, BUF=variable used as an 
input buffer 


FPT_WRITE MSWRITE DCBedcbname, BUF=variable used as an 
output bufter 


FPT_CLOSE MSCLOSE DCB=dcbname 


Examples of each of these macros and the associated monitor service calls are 
given in the attached sample program. An additional macro and monitor service 
call is used in the sample program to change the prompt used when the system 
attempts to get input from a terminal See the PROMPT PROC. 


Certain "refid's take variables as vatues, for example NAME and ACCT above. 
There are macros available to be sure that such variables are in the proper 
form. Some of these are referred to as VLPs (Vector Located parameters). The 
macro used to handle the NAME refid is ZVLP_NAME. There is an example of its 
use in the sample program. 


Because of the complexity of 1/0 in PL-6, you may wish to use FORTRAN 
subroutines to handle the I/0 in your programs. It is not difficult to do 
this; however, there are a few special things that need to be done. The 
following statements must be put in the PL-6 main program. 


DCL XFF_7INITL ENTRY CONV(O) ALTRET; 

CALL XFF_7INITL; 
XFF_7INITL is a FORTRAN initialization Library routine. The CALL should be 
placed in the main program so that it is executed before a call to any FORTRAN 


subroutine. 


ALL FORTRAN subroutine names should be declared using the ENTRY attribute, in 
the form: 


DCL subr-name ENTRY (no-of~-parameters); 
FORTRAN functions cannot be used. The "no-of-parameters" is a maximum; the 
actual FORTRAN subroutine may have fewer. The attributes of the PL-6 


identifiers must match the FORTRAN variable declarations. The following List 
shows the matching attributes. 
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FORTRAN PL-6 


aa ee ee ee ee ee wee we we we we ee ee ee ee 


INTEGER SBIN WORD 

REAL BIT(36) ALIGNED 
DOUBLE PRECISION BIT(72) DALIGNED 
LOGICAL BIT(1) ALIGNED 
CHARACTER«n CHAR(n) 


The second sample program illustrates the use of FORTRAN subroutines to do 
file I/0. Terminal 1/0 and printer output can also be done with FORTRAN 
subroutines. 

NOTE: 


FORTRAN subroutine names must be no more than 8 characters long. Longer names 
are not handled properly when Linking. 
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Appendix A 


Example Program 


EXAMPLE 
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: PROC MAIN; 


/x This program does a Linear search of a file whose 

name is read from the terminal. The file is in the form 
of a symbol table with mnemonic, opcode and type. The 
file is read in before the search begins. The prompt is 
changed for each bit of information that is requested from 
the terminal */ 


DCL 1 OPREC (0:400) STATIC, 


2 MNE CHAR(6), /x Mnemonic for instruction */ 
2 OPCODE UBIN, /x Opcode for instruction */ 
2 ITYPE UBIN; /*x Type for instruction x/ 


DCL FS10 DCB; 
DCL MSSI DCB; 


nr 1A ALO 
MSLO 


VEL VLD, 
DCL COMMAND STATIC CHAR(31); /x terminal buffer */ 
DCL INREC STATIC CHAR (12); /x file buffer */ 


DCL DIGITS CHAR(3); 
DCL HOLD STATIC CHAR(6); 


DCL OUTLINE STATIC CHAR(30); /x output buffer «*/ 
DCL NFOUND CHAR(9) CONSTANT INITC'NOT FOUND'); 

DCL N SBIN; /x number of records */ 

DCL MARK SBIN; /x Location of dot in file name x/ 
DCL FINI SBIN; /x end of input Line «/ 


DCL LOOK STATIC SBIN INIT(-1); /x trial location x*/ 
/x Setting up structures to be used by the monitor calls */ 


ZINCLUDE CP_6; 

%VLP_NAME(FPTN=SOURCE) > 

DCL SACCT CHAR(8) STATIC; 

%FPT_OPEN (FPTN=OPSRCE,FUN=IN,ACCT=SACCT,ASN=FILE, 
NAME=SOURCE,DCB=F$10); 

%FPT_READ (FPTN=OPFILE,BUF=INREC ,DCB=F$10); 

%FPT_READ (FPTN=TTY,BUF=COMMAND ,DCB=MSS1); 

%FPT_WRITE (FPTN=TERM,BUF =OUTLINE,DCB=M$LO); 

%FPT_CLOSE (FPTN=OPFILEC ,DCB=F$10); 
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READ: 
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/* Set the prompt; read the file name; find the dot separator 
and the trailing blank. Then separate the COMMAND string 
into its parts and open the file «/ 


CALL PROMPT('Enter file name: ')>; 
COMMAND = ‘ *; 

CALL MSREAD(TTY); 

CALL INDEX (MARK,'.°,COMMAND); 
CALL INDEX (FINI,* °,COMMAND); 


/* Set length of name string (.L#); put name string in the 
structure (.NAME#); and put account string in SACCT. x/ 


SOURCE .L#=MARK; 

SOURCE.NAME# = SUBSTR( COMMAND ,0,MARK); 

SACCT = SUBSTR( COMMAND ,MARK+1,FINI-MARK-1); 

CALL MSOPENC(COPSRCE); 

/* Read in all the records of the file and keep track of 
how many there were in N. Each record part is moved to the 
appropriate place in OPREC. x/ 


CALL MSREAD (OPFILE); 
N = 0; 


/*x N counts the number of records in the file. The (1=1) test 
a dodge to create an infinite loop. */ 


DO WHILE (1=1); 
OPREC.MNE(N) = SUBSTR(INREC,0,6);  /* note start at O */ 
DIGITS = SUBSTR(INREC,7,3); 
CALL CHARBIN(OPREC.OPCODE(N) ,DIGITS): 
OPREC.ITYPE(N) = ASCBIN(SUBSTR(INREC,11,1))> 


N=N+# 1: 
CALL MSREAD COPFILE) WHENALTRETURN DO; EXIT READ; END; 
END; 


CALL MSCLOSE(OPFILEC); 


/* Change the prompt and Loop through getting instruction 
names to Look up x/ 


CALL PROMPT (‘Enter mnemonic: '); 
DO WHILE (FINI > O AND LOOK ~= 0): 
COMMAND = ‘ ‘3 
CALL MSREAD(TTY); 
CALL INDEX(FINI,' ‘,COMMAND); 
HOLD = SUBSTR(COMMAND,O,FINI); 
LOOK = 0; 
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/* Search through the entries and print a response whether found 
or not x/ 


DO WHILE (OPREC.MNE(LOOK) ~= HOLD AND LOOK < N); 
LOOK = LOOK + 1; 
END; 
IF OPREC.MNE(LOOK) = HOLD THEN 
DO; - 
CALL BINCHAR(DIGITS,OPREC .OPCODE(LOOK)); 
CALL CONCAT (OUTLINE,'’The code is ',DIGITS," The type is ' 


BINASC(OPREC .ITYPE(LOOK) ))> 
END; 
ELSE OUTLINE = NFOUND; 
CALL MSWRITECTERM);> 


/x A search for an ADD instruction ends the loop because 
it is the first mnemonic in the OPREC table. Its entry 
number is zero. */ 


END; 


/x Procedure to change the prompt on reads from the 
terminal. The prompt string is expected to be passed 
as a parameter to this procedure. */ 


PROMPT: PROC(DIS); 
DCL DIS CHAR(20); 
DCL DAT CHAR(20) STATIC; 
DCL SIZ SBIN STATIC; 
ZFPT_PROMPT(FPTN=DOIT,DCB=MSUC ,PROMPT=DAT ) ; 
CALL INDEX (S$12,':',DIS); 
DAT = SUBSTR(DIS,0,S1Z+1); 
CALL MSPROMPT(DOIT); 
RETURN; 
END PROMPT; 


END EXAMPLE; 
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EX_WITH_FOR: PROC MAIN; 


/* This program does a Linear search of a file whose 

name is read from the terminal. The file is in the form 
of a symbol table with mnemonic, opcode and type. The 
file is read in before the search begins. The prompt is 
changed for each bit of information that is requested from 
the terminal. The file is opened, read, and closed 

using FORTRAN subroutines. x*/ 


DCL 1 OPREC (0:400) STATIC, 


2 MNE CHAR(6), /*x Mnemonic for instruction */ 
2 OPCODE UBIN, /*x Opcode for instruction */ 
2 ITYPE UBIN; /* Type for instruction */ 


DCL HOLD STATIC CHAR(6); 

DCL NFOUND CHAR(9) CONSTANT INITC'NOT FOUND’); 

DCL N SBIN; /*x number of records */ 

DCL FINI SBIN; /*x end of input Line «/ 

DCL LOOK STATIC SBIN INIT(-1); /x trial location x/ 
DCL RDTTY ENTRY( 1); 

DCL WRITELN ENTRY(4); 

DCL OPENF ENTRY; 

DCL RDFILE ENTRY (4); 

DCL CLOSEF ENTRY: 

DCL XFF_7INITL ENTRY CONV(O) ALTRET; 

DCL EOF SBIN STATIC INIT(O); /x end of file indicator */ 


/x Set the prompt and read in the file name. 
Then, open the file with the subroutine. «/ 


CALL XFF_7INITL; /x Initialize FORTRAN routines «/ 
CALL PROMPT( ‘Enter file name: '); 

CALL OPENF; 

/x Read in all the records of the file and keep track of 

how many there were in N. Each record part is moved to the 
appropriate place in OPREC. x/ 

N= -1; 


/* N counts the number of records in the file. x«/ 


DO WHILE (EOF=0); 


N=N + 13 
CALL RDFILE(OPREC .MNE(N) ,OPREC.OPCODE(N) ,OPREC.ITYPE(N) ,EOF); 
END; 


CALL CLOSEF; 
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/x Change the prompt and loop through getting instruction 
names to Look up */ 


CALL PROMPT (‘Enter mnemonic: '); 
DO WHILE (FINI > 0 AND LOOK ~= 0); 
CALL RDTTYCHOLD)> 
LOOK = 0; 


/* Search through the entries and print a response whether found 
or not x/ 


DO WHILE (OPREC.MNE(LOOK) ~= HOLD AND LOOK < N); 
LOOK = LOOK + 1; 
END; 
IF OPREC.MNE(LOOK) = HOLD THEN 
CALL WRITELN(OPREC.OPCODE(LOOK) ,O,OPREC.ITYPE(LOOK) ,0); 
ELSE CALL WRITELN(O,NFOUND 0,1); 


/x A search for an ADD instruction ends the loop because 
it is the first mnemonic in the OPREC table. Its entry 
number is zero. */ 


END; 


/*x Procedure to change the prompt on reads from the 
terminal. The prompt string is expected to be passed 
as a parameter to this procedure. */ 


PROMPT: PROC(DIS); 
DCL DIS CHAR(20); 
DCL DAT CHAR(20) STATIC; 
DCL SIZ SBIN STATIC; 
%INCLUDE CP_6; 
%FEPT_PROMPT( FPTN=DOIT ,DCB=MS$UC ,PROMPT=DAT); 
CALL INDEX (SI1Z,':',DIS); 
DAT = SUBSTR(DIS,0,SIZ+1); 
CALL M$PROMPT(DOIT); 
RETURN; 
END PROMPT; 


END EX_WITH_FOR; 


XPQ3-00 


A-5 


31 


AOOO 


21 


19 


ADNOAD 
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Subroutine to open the file 


SUBROUTINE OPENF 
CHARACTER*30 FNAME 

READ 31, FNAME 
FORMAT(A30) i 
OPENCUNIT=10,FILE=FNAME ) 
RETURN 

END 


Subroutine to read a record from the file 
STATUS is set negative on end of file. 


SUBROUTINE RDFILE(MNE,OP,TYPE,STATUS); 
INTEGER STATUS, OP, TYPE 

CHARACTER*6 MNE 

STATUS = O 

READ (10,21,END=19) MNE, OP, TYPE 
FORMAT(A6,1X,13,1X,11) 

RETURN 

STATUS = -1 

RETURN 

END 


Subroutine to close the file 


SUBROUTINE CLOSEF 
CLOSE( 10) 

RETURN 

END 


Subroutine to read a mnemonic from the terminal 


SUBROUTINE RDTTY(COM) 
CHARACTER*6 COM 

READ 20, COM 

FORMAT( A6) 

RETURN 

END 


Subroutine to print the results 


IND indicates whether to print MSG or CODE and TYPE 


SUBROUTINE WRITELN(CODE,MSG,TYPE,IND) 
CHARACTER*9 MSG 

INTEGER CODE, TYPE, IND 

IF (IND .EQ. 0) THEN 


20 


21 


PRINT 20, CODE, TYPE 
FORMAT(' The code is ',13,' The type is ',I1/) 
ELSE ; 
PRINT 21, MSG 
FORMAT(’ ',A9/) 
ENDIF 
RETURN 
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Appendix B 


PL-6 Reserved 


ADDR 
ALIGNED 
ALTRET 
ALTRETURN 
AND 
AREADEF 
AREAREF 
ASCBIN 
ASCBIT 
ASYNC 
AUTO 
AVOID 


BASED 
BINASC 


BIruoIir 
BAND. 


BINCHAR 
BINXCHAR 
BIT 
BITASC 
BITBIN 
BITDSCR 
BITVECT 
BY 

BYTE 


CALIGNED 
CALL 
CASE 
CHAR 
CHARBIN 
CONCAT 
CONSTANT 
CONV 
CPTR 
CSTARTx 


xThese keywords are not 


DALIGNED 
DBASE 
DBOUND 
DCB 
DCBADDR 
DCBNUM 
DCL 


EDITCHAR 


CANA TTCTO 
evaiioin 


EDITXCHAR 
ELSE 
END 
ENTADDR 
ENTRY 
EPTR 
ERASE 
ESTART* 
EXIT 
EXT 
EXTROOT 


FOR 
GOTO 
HALF 


HALIGNED 
HSTART* 


the near future. 
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part of PL-6 yet; but they will probably be adopted in 


Keywords 
IF PALIGND 
IN PALIGNW 
INDEX PINCRB 
INDEX 1 PINCRC 
INDEX1R PINCRW 
INDEX2 POFFC 
INDEX2R POFFW 
INHIBIT PRIVY 
INIT PROC 
INSERT PSTARTx 
PTR 
LENGTHB 
LENGTHC READONLY 
LENGTHV REDEF 
LENGTHW REMEMBER 
RETURN 
MAIN 
MATERIALIZE SBIN 
MAXIMUM SEARCH 
MINIMUM SEARCHR 
MOD SELECT 
SIZEB 
NIL SIZEC 
NOAUTO SIZEV 
NOT SIZEW 
SPOIL 
OFF STATIC 
ON SUBSTR 
OPTIONAL SYMDEF 
OR SYMREF 
THEN 
TO 
THRU* 


UBIN 

UNAL 
UNINHIBIT 
UNTIL 
UNWIND 
USE 


VBASE 
VBOUND 
VFLAGS 
VECTOR 
VTYPE 


WALIGNED 
WHENALTRETURN 


WUHENRETURN 


PTOUUN ES FN 


WHILE 
WORD 
WSTARTx 


XCHARBIN 
XLATE 
XLATE_6_T0_9 
XLATE_9_TO_6 


$PR5 
$PR6 
$PR7 
$X5 
$X6 
$X7 


Index 


Assignment Statements - 1-6 


Based Data Structures - 1-5 

Basic Forms - 1-1 

Braces - viii 

Brackets - viii 

Built-in Functions and Subroutines - 1-11 


Capital Letters - vii 
Control Statements - 1-7 


Declarations - 1-2 


Horizontal Ellipsis - ix 


Input and Output - 1-14 


OR Bar - viii 
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Procedure Related Statements - 1-9 


Scope of Variables - 1-10 
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Vertical Ellipsis - ix 


i-2 


XP03-00 


